Ports are carriers for pixel data. Examples of ports are screen and printer ports.
Riders are access paths to ports. The drawing operations of a rider are performed in a coordinate system with positive x-axis and negative y-axis, i.e. x values increase towards the right, while y values increase towards the bottom. This coordinate system is the same for every rider on a port, with the origin at the upper-left corner of the port. Points are coordinate pairs (in device coordinates) which denote the upper-left corner of a pixel:
Picture a: Drawing Plane
A rider occupies a rectangle within the port area. Each rider acts as a clipping rectangle, to which all its drawing operations are clipped.
Frames are port mappers, which provide port output operations and input from mouse and keyboard. Frame coordinates are scaled and translated such that they are independent of the frame's position on a port, and independent of the port's spacial resolution.
This is a pseudo color which is substituted by the currently set default foreground color for drawing.
CONST mm, point, inch
Three important distance measures in universal units.
CONST fill
This value may be passed to the procedures DrawRect, DrawOval, DrawPath, and MarkRect as size parameter, to cause the drawing of a filled shape, instead of the shape's outline only.
These values may be passed to the procedure DrawPath as path parameter. They causes the drawing of a polyline, a polygon, an open Bezier curve, or of a closed Bezier curve. Note that with Bezier curves, only every third point lies on the curve.
Picture b: Various Path Examples
CONST invert, hilite, dim25, dim50, dim75
These values may be passed as mode-parameter to procedure MarkRect. They cause the marked rectangle to become inverted, hilighted, or dimmed. The exact interpretation of these modes is platform-dependent. However, they should alter the display visibly, and they must be invertable. This means that successively drawing a pixel in the same mode twice results in the pixel having the same color as before, provided that no other drawing operation has been performed there in between.
In the simplest case, all three modes are implemented the same way, namely by inverting each bit in the color value which represents a pixel. Ideally, hilite should replace an area's background color with a user-selectable hilight-color, and vice versa. The three dimming modes, applied to a white background, deliver light, medium, and dark grey values, respectively.
CONST hide, show
These values may be passed as show-parameter of the MarkRect procedures. hide means that an existing mark should be removed, and show means that the mark should be drawn.
Cursor shapes which correspond to the type of data currently being manipulated: sequential, large shapes, regularly arranged objects, small shapes.
CONST keepBuffer, disposeBuffer
These constants may be passed to the dispose parameters of procedures Rider.RestoreRect and Frame.RestoreRect.
TYPE LONGCHAR
Type for 2-byte characters in the Unicode character set.
TYPE Color = LONGINT
A color is a four-byte value where the least significant byte (interpreted as unsigned integer) specifies the red-intensity of an RGB triple. The next byte specifies the green-intensity, the third byte represents the blue-intensity. The most significant byte must be set to zero.
TYPE Point
This type is used to construct paths for the DrawPath procedure. A path consists of an array of points, where points are coordinate pairs.
Points are used in drawing routines that call DrawPath.
Points are not extended.
x, y: LONGINT
Coordinate pair.
TYPE Port
Interface
Carrier for pixel data.
Ports are allocated and used internally.
Ports are extended internally.
unit-: LONGINT unit > 0
The size of a pixel in universal units.
w-, h-: LONGINT w >= 0 & h >= 0 [pixels]
Width and height of the port in pixels.
PROCEDURE (p: Port) Init (unit: LONGINT)
Sets the spacial resolution (in universal units per pixel).
p.unit = 0 OR p.unit = unit 20
unit > 0 21
p.unit = unit
PROCEDURE (p: Port) SetSize (w, h: LONGINT)
Sets the port's size, in pixels.
w >= 0 20
h >= 0 21
p.w = w
p.h = h
PROCEDURE (p: Port) NewRider (): Rider
Interface
Returns a rider which has the appropriate type for this port implementation.
Opens an off-screen buffer for port p. The buffer is initialized with the contents of p's rectangle (l, t, r, b). OpenBuffer must be followed by a call to CloseBuffer. Calls to OpenBuffer must not be nested.
PROCEDURE (p: Port) CloseBuffer
Interface
Copy back the contents of the port's off-screen buffer, and release the buffer. OpenBuffer must have been called before.
TYPE Rider
Interface
Access path to a port (i.e. to a pixel carrier). A rider uses the same coordinate system as its port, with the origin being the upper-left corner of the port. All coordinates used for a rider are in device coordinates, i.e. in pixels.
Riders are allocated by ports.
Riders are used and extended internally.
l-, t-, r-, b-: LONGINT 0 <= l <= r & 0 <= t <= b [pixels]
Saves a rectangle (parallel to the coordinate axes) of width r - l and of height b - t in a background buffer, from where it can be restored later using RestoreRect. SaveRect must be balanced by RestoreRect(l, t, r, b, disposeBuffer). Calls to SaveRect may not be nested. res = 0 means that the call was successful, otherwise RestoreRect must not be called.
After a successful call to SaveRect, the same rectangle, i.e. its pixelmap contents as it was upon saving, can be restored with RestoreRect. RestoreRect can be called several times in succession; the last time with dispose = disposeBuffer and all other times with dispose = keepBuffer.
Draws a rectangle (parallel to the coordinate axes) of width r - l and of height b - t. If s < 0, the rectangle is filled with color col. Otherwise, the rectangle is drawn as an outline of thickness s. The outline is drawn inside of the rectangle. If s = 0, a very thin outline (hairline) is used.
Draws an ellipse (parallel to the coordinate axes) of width r - l and of height b - t. If s < 0, the ellipse is filled with color col. Otherwise, the ellipse is drawn as an outline of thickness s. The outline is drawn inside of the rectangle. If s = 0, a very thin outline (hairline) is used.
Draws a line from the point (x0, y0) to the point (x1, y1) of thickness s in color col:
Picture c: Line
If s = 0, a very thin outline (hairline) is used.
s >= 0 20
PROCEDURE (rd: Rider) DrawPath (VAR p: ARRAY OF Point; n, s: LONGINT; col: Color;
path: INTEGER)
Interface
Draws the path consisting of points p[0] .. p[n - 1] in color col. The nature of the path is given by parameter path. It can either be a polyline, a polygon, an open Bezier curve, or a closed Bezier curve. The polyline is the same that a sequence of DrawLine operations would generate. For a polygon, the n points define the mathematical region which will be outlined or filled. An open path with n points results in n - 1 path pieces, a closed path with n points results in n path pieces.
Marks a rectangle (parallel to the coordinate axes) of width r - l and of height b - t. If s < 0, the rectangle is filled with color col. Otherwise, the rectangle is drawn as an outline of thickness s. The outline is drawn inside of the rectangle. If s = 0, a very thin outline (hairline) is used.
The meaning of mode is implementation-dependent, but it must change the marked area in a visible way, and it must be invertable. show indicates whether the mark should be drawn or removed.
mode IN {invert, hilite, dim25, dim50, dim75} 20
PROCEDURE (rd: Rider) Scroll (dx, dy: LONGINT)
Interface
Shifts the rider's contents by vector (dx, dy). Shifting occurs completely within the rider's rectangle, ie. pixels outside of it are neither written nor read. The part of the rectangle which becomes newly exposed is undefined.
The purpose of Scroll is to speed up scrolling operations by reusing existing pixel data instead of making the application redraw everything.
However, under special circumstances, this procedure may not actually copy pixel data, but cause the application to restore part of the rectangle instead anyway.
Warning: this operation may only be used on interactive ports, in order to update the screen display after a user manipulation.
Polls the current mouse location and tells whether the mouse button is currently pressed. In modifiers, the currently pressed modifier keys are returned, like Controllers.doubleClick, Controllers.extend, Controllers.modify, and possibly additional platform-specific modifiers.
PROCEDURE (rd: Rider) DrawString (x, y: LONGINT; col: Color; VAR s: ARRAY OF CHAR;
font: Fonts.Font);
Interface
Draws string s in color col and font font with the base line at y.
Warning: the contents of parameter s may be changed by the operation.
Draws string s in color col and font font with the base line at y.
Warning: the contents of parameter s may be changed by the operation.
font # NIL 20
PROCEDURE (rd: Rider) CharIndex (x, pos: LONGINT; VAR s: ARRAY OF CHAR;
font: Fonts.Font): LONGINT
Interface
Given string s at position x, CharIndex determines the index of the character which lies at position pos. Result = 0 means pos is at or left of the first character in s, result = n - 1, where n is the number of characters in string s, means pos is right of the last character in s.
Warning: the contents of parameter s may be changed by the operation.
font # NIL 20
PROCEDURE (rd: Rider) LCharIndex (x, pos: LONGINT; VAR s: ARRAY OF LONGCHAR;
font: Fonts.Font): LONGINT
Interface
Given string s at position x, CharIndex determines the index of the character which lies at position pos. Result = 0 means pos is at or left of the first character in s, result = n - 1, where n is the number of characters in string s, means pos is right of the last character in s.
Warning: the contents of parameter s may be changed by the operation.
font # NIL 20
PROCEDURE (rd: Rider) CharPos (x, index: LONGINT; VAR s: ARRAY OF CHAR;
font: Fonts.Font): LONGINT
Interface
Given string s at position x, CharPos determines the position of character index in s. The position of the left margin of the character is returned.
Warning: the contents of parameter s may be changed by the operation.
font # NIL 20
PROCEDURE (rd: Rider) LCharPos (x, index: LONGINT; VAR s: ARRAY OF LONGCHAR;
font: Fonts.Font): LONGINT
Interface
Given string s at position x, CharPos determines the position of character index in s. The position of the left margin of the character is returned.
Warning: the contents of parameter s may be changed by the operation.
font # NIL 20
TYPE Frame
A Frame is a mapper for a port. Every frame has its own coordinate system. All coordinates used for a frame are measured in universal units. Most frame operations forward to the frame's rider, i.e. they call the frame rider's corresponding procedure, and perform the necessary coordinate transformations (scaling between universal units and pixels, and a translation by the frame's origin).
Frames are allocated by views.
Frames are used by views, for drawing and for mouse polling.
Frames are extended internally (Views.Frame).
unit-: LONGINT unit > 0
The size of a pixel in universal units.
dot-: LONGINT dot = point - unit MOD point
This value can be used as an approximation of point, rounded to a pixel. By using dot instead of point, ugly rounding errors can be avoided.
rider-: Ports.Rider
Rider which links the frame to a port.
gx-, gy-: LONGINT [units]
The frame's origin in global coordinates (i.e. relative to the port's upper-left corner), but in units.
PROCEDURE (f: Frame) ConnectTo (p: Port)
Connects the frame to a port. All other frame procedures require a connected frame, i.e. rider # NIL. This precondition is not checked explicitly.
ConnectTo is used internally.
p = NIL
f.unit = 0
f.rider = NIL
p # NIL
f.unit = p.Base().unit
f.rider # NIL & f.rider.Base() = p
PROCEDURE (f: Frame) SetOffset (gx, gy: LONGINT)
Sets the frame's origin, in global coordinates and units. All local coordinates are relative to this origin.
Saves a rectangle (parallel to the coordinate axes) of width r - l and of height b - t in a background buffer, from where it can be restored later using RestoreRect. SaveRect must be balanced by RestoreRect(l, t, r, b, disposeBuffer). Calls to SaveRect may not be nested. res = 0 means that the call was successful, otherwise RestoreRect must not be called.
After a successful call to SaveRect, the same rectangle, i.e. its pixelmap contents as it was upon saving, can be restored with RestoreRect. RestoreRect can be called several times in succession; the last time with dispose = disposeBuffer and all other times with dispose = keepBuffer.
Draws a rectangle (parallel to the coordinate axes) of width r - l and of height b - t. If s < 0, the rectangle is filled with color col. Otherwise, the rectangle is drawn as an outline of thickness s. The outline is drawn inside of the rectangle. If s = 0, a very thin outline (hairline) is used.
Draws an ellipse (parallel to the coordinate axes) of width r - l and of height b - t. If s < 0, the ellipse is filled with color col. Otherwise, the ellipse is drawn as an outline of thickness s. The outline is drawn inside of the rectangle. If s = 0, a very thin outline (hairline) is used.
Draws a line from the point (x0, y0) to the point (x1, y1) of thickness s in color col:
Picture e: Line
If s = 0, a very thin outline (hairline) is used.
s >= 0 20
PROCEDURE (f: Frame) DrawPath (VAR p: ARRAY OF Point; n, s: LONGINT; col: Color;
path: INTEGER)
Draws the path consisting of points p[0] .. p[n - 1] in color col. The nature of the path is given by parameter path. It can either be a polyline, a polygon, an open Bezier curve, or a closed Bezier curve. The polyline is the same that a sequence of DrawLine operations would generate. For a polygon, the n points define the mathematical region which will be outlined or filled. An open path with n points results in n - 1 path pieces, a closed path with n points results in n path pieces.
Marks a rectangle (parallel to the coordinate axes) of width r - l and of height b - t. If s < 0, the rectangle is filled with color col. Otherwise, the rectangle is drawn as an outline of thickness s. The outline is drawn inside of the rectangle.
The meaning of mode is implementation-dependent, but it must change the marked area in a visible way, and it must be involutory. If s = 0, a very thin outline (hairline) is used. show indicates whether the mark should be drawn or removed.
mode IN {invert, hilite, dim25, dim50, dim75} 20
PROCEDURE (f: Frame) Scroll (dx, dy: LONGINT)
Shifts the frame's area by vector (dx, dy). Shifting occurs completely within the frame's rectangle, ie. pixels outside of it are neither written nor read. The part of the rectangle which becomes newly exposed should be considered as undefined.
The purpose of Scroll is to speed up scrolling and editing operations by reusing existing pixel data instead of making the application redraw everything.
However, under special circumstances, this procedure may not actually copy pixel data, but cause the application to restore part of the rectangle instead anyway.
Warning: this operation may only be used on interactive ports, in order to update the screen display after a user manipulation.
Picture f: Effect of Scroll Operation
PROCEDURE (f: Frame) SetCursor (cursor: INTEGER)
Sets the cursor to the given value.
SetCursor is used in polling loops during mouse tracking.
cursor IN {arrowCursor..resizeCursor} 20
PROCEDURE (f: Frame) Input (VAR x, y: LONGINT; VAR modifiers: SET; VAR isDown: BOOLEAN)
Polls the current mouse location and tells whether the mouse button is currently pressed.
Input is used in polling loops during mouse tracking. In modifiers, the currently pressed modifier keys are returned, like Controllers.doubleClick, Controllers.extend, Controllers.modify, and possibly additional platform-specific modifiers.
Given string s at position x, CharIndex determines the index of the character which lies at position pos. Result = 0 means pos is at or left of the first character in s, result = n - 1, where n is the number of characters in string s, means pos is right of the last character in s.
Given string s at position x, CharIndex determines the index of the character which lies at position pos. Result = 0 means pos is at or left of the first character in s, result = n - 1, where n is the number of characters in string s, means pos is right of the last character in s.
(.txt)